Contents page

Rules for Tools/Quick Tour

Tools
     Each Tool in the ToolBox is composed of the Tool's icon, name, and
     a collection of routines that describe the behavior of the Tool.
     One routine operates on events that pass through the Tool on their
     journey through the PipeLine.  Another opens a control window when
     the user double clicks on the Tool's icon in a PipeLine.  A Tool is
     actually composed of two parts - the Tool structure and the
     ToolMaster structure.  The ToolMaster structure provides all of
     the general information about a Tool, including the
     above-mentioned routines and images.  When the user drags a Tool
     into a Track, a new data structure is invoked: the Tool structure.
     Each instance of a Tool in a PipeLine is represented by a unique
     Tool structure that carries information specific to this instance
     of the Tool.  For example, a Delay Tool in a PipeLine carries the
     delay time within the Tool itself because several Delay Tools can
     have different delay times.  Yet the delay mechanism, the routine
     that creates a delay, is stored in the ToolMaster. See Tools.

Events
     The events processed by Tools are MIDI voice events.  These
     include all of the standard MIDI performance events:  Note On/Off,
     Pitch Bend, Control Change, Mono After-Touch, Poly After-Touch, and
     Program Change (see MIDI Status Types).  Each event is stored in a
     structure that carries, in addition to the MIDI information, the
     time the event occurs and the for which Tool it is destined.
     Bars&Pipes provides a system for allocating and freeing events.
     See Events.

Tracks
     Each Bars&Pipes Track is composed of a Track structure and a
     linked list of Tools.  As notes flow through the PipeLine, they
     pass from one Tool to the next.  In the center of the PipeLine is
     a special Tool, the Sequencer, which records notes entering it
     from the Tools on the left and plays them back by sending them on
     to the list of Tools on the right.  The Sequencer Tool stores the
     recorded notes directly in the Track structure. See Tracks.

Clips
     Bars&Pipes uses a standard structure, the Clip structure, for
     storing a sequence of MIDI events.  The Clip structure also carries
     Lyrics, Dynamics, and other Song Parameters, each in a separate
     linked list.  Each Track carries two Clip structures, one to store
     the sequence, the second to store the Undo buffer. See Clips.

PipeLine Handler
     The PipeLine Handler takes MIDI Events and passes them through the
     PipeLines.  Carrying each Event from one Tool to the next, the
     Handler presents the Event to each Tool's routine for processing
     individual Events.  In turn, the routine receives the Event,
     stamps the address of the next Tool for which the Event is
     destined, and returns the Event to the PipeLine Handler.  Should
     the Tool need to return more than one Event to the Handler (for
     example, the CounterPoint Tool returns a counter melody in
     addition to the original note,) it returns them as a linked list
     of events.  If, on the other hand, the Tool throws the Event away
     (for example, a filter Tool would do this,) it deallocates the
     Event and returns a `NULL' pointer to the PipeLine Handler.

     The PipeLine Handler is always running, passing events from Tool to
     Tool, regardless of whether the Transport is moving.  This allows
     the user to play music and work with Tools without actually
     running the Sequencer.

     Usually, the PipeLine passes Events from Tool to Tool as soon as
     they enter it, so they can be processed as quickly as possible.
     Any Tool, however, that needs to process Events EXACTLY at the
     time-stamp time (for example, the MIDI Out Tool,) can do so by
     setting a flag which tells the PipeLine to release Events to these
     Tools only when their time has arrived.  This mechanism allows the
     sequencer to pre-release large blocks of notes so that they can be
     processed in advance by Tools in the PipeLine, then queued for
     timed release at their final destination, the MIDI Out Tool.

Accessories
     Unlike Tools, which are intended specifically to process musical
     information, Accessories are much more general in scope.  They may
     be used to complement the list of Bars&Pipes' built-in features in
     any way imaginable.  Like Tools, each Accessory is defined by an
     icon and a set of routines that describes its behavior.  These
     routines include routines that Bars&Pipes calls when the user
     opens Accessory's control window, as well as optional routines for
     loading and saving the Accessory's data as part of a song.  (On
     the other hand, a Tool itself is saved as part of a song.) See
     Accessories.

Functions
     Bars&Pipes provides an extensive library of functions that can be
     called by each Tool and Accessory.  These include routines to
     allocate and deallocate Events, translate from MIDI into key and
     scale, and open a scrolling pop-up menu from which the user can.
     Bars&Pipes maintains a central data structure called "Functions"
     that, in addition to holding all of Bars&Pipe's global data
     structures, contains a set of pointers to each of the functions in
     the library. See Functions Structure.

Transport Handler
     Bars&Pipes maintains a list of modules that are controlled by the
     sequencer mechanism, the Transport Handler. When the user clicks
     on Start, Stop, or any other of the Transport controls, the
     Transport Handler notifies each module in the list by calling a
     routine provided by the module itself.  Both Tools and Accessories
     may insert routines in the Transport Handler's list, so that they
     can run in synch with the rest of Bars&Pipes. See
     Transport Handlers.

   Now that we've discussed the key concepts, we'll discuss each in greater depth.